
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.Collections.Generic;
using System.Text;
using System.Xml;

namespace Swaf.Crypto
{
    public interface IX509XmlCrypto
    {
        IDictionary<String, ICertificateInfo> Certificates { get; }

        /// <summary>
        /// This method is expected to take in a clear string containing an XML element's
        /// InnerXml or InnerText.  It will return and EncryptedData XML element as a String.
        /// 
        /// Generally this would be used with a XmlTextReader and the result String would be written
        /// to the XmlTextReader.
        /// </summary>
        /// <param name="certNameOrSubject">CSF name of the certificate to use or the subject to locate the cert in an X509Store, for instance 'CN=MyCert'.</param>
        /// <param name="elementName">Name of the element in the Xml that is going to be encrypted</param>
        /// <param name="clearElementString">The contents of the element in clear text format</param>
        /// <returns>The resulting EncryptedData Xml element</EncryptedData></returns>
        String Encrypt(String certNameOrSubject, String elementName, String clearElementString);

        /// <summary>
        /// This method is expected to take in a clear string containing an XML element's
        /// InnerXml or InnerText.  It will write the corresponding XML to the writer provided.
        /// </summary>
        /// <param name="certNameOrSubject">CSF name of the certificate to use or the subject to locate the cert in an X509Store, for instance 'CN=MyCert'.</param>
        /// <param name="writer">XmlTextWriter to receive the EncryptedData element</param>
        /// <param name="elementName">The name of the element who's contents will be encrypted</param>
        /// <param name="clearElementString">Contents of the xml element in clear unencrypted format</param>
        void Encrypt(String certNameOrSubject, XmlTextWriter writer, String elementName, String clearElementString);

        /// <summary>
        /// This method is expected to take in a clear string containing an XML element's
        /// InnerXml or InnerText.  It will return and EncryptedData XML element as an XmlElement.
        /// 
        /// This method is generally used when you have clear text XML that you want in XmlElement format
        /// to be added to an Xml DOM.
        /// </summary>
        /// <param name="certNameOrSubject">CSF name of the certificate to use or the subject to locate the cert in an X509Store, for instance 'CN=MyCert'.</param>
        /// <param name="elementName">Name of the element in the Xml that is going to be encrypted</param>
        /// <param name="clearElementString">The contents of the element in clear text format</param>
        /// <returns>The XmlElement that can be added to an Xml Document</returns>
        void Encrypt(String certNameOrSubject, String elementName, String clearElementString, out XmlElement encXmlElement);

        /// <summary>
        /// This method will encrypt an XmlElement and return an EncryptedData Xml element by encrypting 
        /// the provided element and returning the results.
        /// </summary>
        /// <param name="certNameOrSubject">CSF name of the certificate to use or the subject to locate the cert in an X509Store, for instance 'CN=MyCert'.</param>
        /// <param name="element">element that is clear but want to have encrypted</param>
        /// <returns>returns an encrypted element</returns>
        XmlElement Encrypt(String certNameOrSubject, XmlElement element);

        /// <summary>
        /// This method will decrypt an Xml Element string and return the clear text XML element String.
        /// 
        /// This is generally used when you have read from an XmlTextReader.
        /// </summary>
        /// <param name="encryptedElementString">The encrypted Xml Element string that needs to be decrypted</param>
        /// <returns>A clear text Xml Element string is returned</returns>
        String Decrypt(String encryptedElementString);

        /// <summary>
        /// This method will take an XmlDocument and decrypt all EncryptedData elements in the Xml document replacing
        /// the encrypted Xml elements with clear text elements.
        /// </summary>
        /// <param name="docWithEncryptedData">Xml Document containing the encrypted elements</param>
        void Decrypt(XmlDocument docWithEncryptedData);
    }
}
